<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Library Implementation</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="index.html" title="Safe Numerics">
<link rel="prev" href="exception_safety.html" title="Exception Safety">
<link rel="next" href="checked_result.html" title="checked_result&lt;R&gt;">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="exception_safety.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="checked_result.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="safe_numerics.library_implementation"></a>Library Implementation</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="checked_result.html">checked_result&lt;R&gt;</a></span></dt>
<dt><span class="section"><a href="checked_arithmetic.html">Checked Arithmetic</a></span></dt>
<dt><span class="section"><a href="interval.html">interval&lt;R&gt;</a></span></dt>
<dt><span class="section"><a href="checked_integer_arithmetic.html">safe_compare&lt;T, U&gt;</a></span></dt>
</dl></div>
<p>This library should compile and run correctly on any conforming
    C++14 compiler.</p>
<p>The Safe Numerics library is implemented in terms of some more
    fundamental software components described here. It is not necessary to
    know about these components to use the library. This information has been
    included to help those who want to understand how the library works so
    they can extend it, correct bugs in it, or understand its limitations.
    These components are also interesting and likely useful in their own
    right. For all these reasons, they are documented here.</p>
<p>In general terms, the library works in the following manner:</p>
<p>At compile time:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The library defines "safe" versions of C++ primitive arithmetic
        types such as <code class="computeroutput">int</code>, <code class="computeroutput">unsigned int</code>, etc.</p></li>
<li class="listitem"><p>Arithmetic operators are defined for these "safe" types. These
        operators are enhanced versions of the standard C/C++ implementations.
        These operators are declared and implemented in the files "<a href="../../include/boost/safe_numerics/safe_base.hpp" target="_top">safe_base.hpp</a>"
        and "<a href="../../include/boost/safe_numerics/safe_base_operations.hpp" target="_top">safe_base_operations.hpp</a>".</p></li>
<li class="listitem"><p>For binary operators, verify that both operands have the same
        promotion and and exception handling policies. If they don't, invoke
        compilation error.</p></li>
<li class="listitem"><p>Invoke the promotion policy to determine the result type R of
        the operation.</p></li>
<li class="listitem"><p>For each operand of type T retrieve the range of values from
        <code class="computeroutput">std::numeric_limits&lt;T&gt;::min()</code> and
        <code class="computeroutput">std::numeric_limits&lt;T&gt;::max()</code>. A range is a pair of
        values representing a closed interval with a minimum and maximum
        value.</p></li>
<li class="listitem"><p>These ranges are cast to equivalent values of the result type,
        R. It's possible that values cannot be cast to the result type so the
        result of the cast is returned as a variant type, <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.
        <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>
        may hold either a value of type R or a <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a>
        value indicating why the cast could not be accomplished. Ranges are
        represented as a pair of values of the type <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.</p></li>
<li class="listitem"><p><a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>
        can be considered enhanced versions of the underlying type R.
        Operations which are legal on values of type R such as +, -, ... are
        also legal on values of <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.
        The difference is that the latter can record operation failures and
        propagate such failures to subsequent operations.<a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>
        is implemented in the header file "<a href="../../include/boost/safe_numerics/checked_result.hpp" target="_top">checked_result.hpp</a>".
        Operations on such types are implemented in "<a href="../../include/boost/safe_numerics/checked_result_operations.hpp" target="_top">checked_result_operations.hpp</a>".</p></li>
<li class="listitem"><p>Given the ranges of the operands, determine the range of the
        result of the operation using compile-time interval arithmetic. The
        <code class="computeroutput">constexpr</code> facility of C++14 permits the range of the
        result to be calculated at compile time. Interval arithmetic is
        implemented in the header file "<a href="../../include/boost/safe_numerics/interval.hpp" target="_top">interval.hpp</a>".
        The range of the result is also represented as a pair of values of the
        type <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.</p></li>
<li class="listitem"><p>Operations on primitives are implemented via free standing
        functions described as <a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>.
        These operations will return instances of <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>
        .</p></li>
</ul></div>
<p>At run time:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>If the range of the result type includes only arithmetically
        valid values, the operation is guaranteed to produce an arithmetically
        correct result and no runtime checking is necessary. The operation
        invokes the original built-in C/C++ operation and returns the result
        value.</p></li>
<li class="listitem"><p>Otherwise, operands are cast to the result type, R, according to
        the selected promotion policy. These "checked" cast operations return
        values of type <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.</p></li>
<li class="listitem"><p>If either of the casting operations fails, an exception is
        handled in accordance with the exception policy.</p></li>
<li class="listitem"><p>Otherwise, the operation is performed using "<a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>".
        These free functions mirror the normal operators +, -, *, ... except
        that rather than returning values of type R, they return values of the
        type <a class="link" href="checked_result.html" title="checked_result&lt;R&gt;"><code class="computeroutput">checked_result&lt;R&gt;</code></a>.
        They are defined in files "<a href="../../include/boost/safe_numerics/checked_default.hpp" target="_top">checked_default.hpp</a>",
        "<a href="../../include/boost/safe_numerics/checked_integer.hpp" target="_top">checked_integer.hpp</a>"
        ,"<a href="../../include/boost/safe_numerics/checked_float.hpp" target="_top">checked_float.hpp</a>".</p></li>
<li class="listitem"><p>If the operation is not successful, the designated exception
        policy function is invoked.</p></li>
<li class="listitem"><p>Otherwise, the result value is returned as a
        <code class="computeroutput">safe&lt;R&gt;</code> type with the above calculated result
        range.</p></li>
</ul></div>
<p>The following components realize the design described here.</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="exception_safety.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="checked_result.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
